[CC1] Give names that reveal the purpose of things.

1

width = x_right - x_left

Next:

1

width = x_right - x_left + 10

Next:

1

width = x_right - x_left + 10

Where does '10' come from?

What does it represent?

Can I change it?

Next:

1

width = x_right - x_left + 10

Where does '10' come from?

What does it represent?

Can I change it?

1

width = x_right - x_left + 2 * horizontal_margin

Next:

1

width = x_right - x_left + 10

Where does '10' come from?

What does it represent?

Can I change it?

1

width = x_right - x_left + 2 * horizontal_margin

[CC1] Replace magic numbers with named variables, parameters, or constants

[CC1] Replace magic numbers…

1
2

def width_with_margins(x_right, x_left):
    return x_right - x_left + 10

[CC1] Replace magic numbers…

1
2

def width_with_margins(x_right, x_left):
    return x_right - x_left + 10

…with named parameters

1
2

def width_with_margins(x_right, x_left, horizontal_margin=5):
    return x_right - x_left + 2 * horizontal_margin

[CC1] Replace magic numbers…

1
2

def width_with_margins(x_right, x_left):
    return x_right - x_left + 10

…with named parameters

1
2

def width_with_margins(x_right, x_left, horizontal_margin=5):
    return x_right - x_left + 2 * horizontal_margin

[CC1] Replace magic numbers…

1

width = width * 0.3937007874

[CC1] Replace magic numbers…

1
2

def width_with_margins(x_right, x_left):
    return x_right - x_left + 10

…with named parameters

1
2

def width_with_margins(x_right, x_left, horizontal_margin=5):
    return x_right - x_left + 2 * horizontal_margin

[CC1] Replace magic numbers…

1

width = width * 0.3937007874

…with named constants

1

width_inches = width_cm * INCHES_PER_CENTIMETER

Example from a past lecture:

1

check_divisible(a, b)

Example from a past lecture:

1

check_divisible(a, b)

What do you think this does?

Example from a past lecture:

1

check_divisible(a, b)

What do you think this does?

• [CC1] Function names should say what they do

The implementation:

1
2
3

def check_divisible(n, divisor):
    if (n % divisor == 0):
        print(n, ' is divisible by ', divisor)

The implementation:

1
2
3

def check_divisible(n, divisor):
    if (n % divisor == 0):
        print(n, ' is divisible by ', divisor)

Misleading name: I don't expect "something that checks" to print anything

A more accurate name:

1
2
3

def print_if_divisible(n, divisor):
    if (n % divisor == 0):
        print(n, ' is divisible by ', divisor)

A more accurate name:

1
2
3

def print_if_divisible(n, divisor):
    if (n % divisor == 0):
        print(n, ' is divisible by ', divisor)

• [CC1] Function names should say what they do

• [CC1] Function names should reveal side-effects (such as printing to the console)

Another function call:

1

remove(l, n)

What do you think this does?

Another function call:

1

remove(l, n)

What do you think this does? Ambiguous name:

• Does it remove the element in l whose value is equal to n?
• Or does it remove the element in l at index n?

An unambiguous name:

1

remove_list_element_at_index(l, i)

An unambiguous name:

1

remove_list_element_at_index(l, i)

• [CC1] Choose unambiguous names
• Clarity at the point of use is more important than brevity
• Include all the words needed to avoid ambiguity from the perspective of someone calling the function
• A general naming template: verb_keywords (the verb indicates what the function does, the keywords what parameters are expected)

Two function calls:

1
2

add_number(a , b)
add_list(c, d)

What do you think these do?

The implementation of the functions:

1
2
3
4
5

def add_number(a , b):
    return a + b

def add_list(l, e):
    l.append(e)

The implementation of the functions:

1
2
3
4
5

def add_number(a , b):
    return a + b

def add_list(l, e):
    l.append(e)

Confusing to use the same word "add" for the two functions:

• in the first case, add calculates the addition
• in the second case, add inserts an element
• in the first case, add has no side effects, in the second, it does!

A way to remove the confusion:

1
2
3
4
5

def add_numbers(a , b):
    return a + b

def append_element_to_list(e, l):
    l.append(e)

A way to remove the confusion:

1
2
3
4
5

def add_numbers(a , b):
    return a + b

def append_element_to_list(e, l):
    l.append(e)

• [CC1] Use different words for different concepts

Another function call:

1

distance(couple_1, couple_2)

What is this about?

Another function call:

1

distance(couple_1, couple_2)

What is this about? Unclear:

• What do couple_1 and couple_2 represent?
• A "couple" could stand for many things: a point in 2D geometry, an interval, a complex number, a rational number...

Another function call:

1

distance(couple_1, couple_2)

Problem: we are mixing two levels of description

• Level 1: the distance between some objects
• Level 2: the implementation of these objects as couples

A way to remove the confusion:

1

distance(point_1, point_2)

• [CC1] Use the appropriate level of description

A way to remove the confusion:

1

distance(point_1, point_2)

• [CC1] Use the appropriate level of description
• If your program uses more than one kind of distance (e.g. between points and between intervals), the name "distance" is not precise enough.
  • Note that the function name does not include the argument names, since the caller can choose any other names.

A way to specify which kind of distance is computed:

1
2

distance_between_points(point_1, point_2)
distance_between_intervals(interval_1, interval_2)

• [CC1] Use the appropriate level of description

Let's revisit an earlier example:

1
2
3

def print_if_divisible(n, divisor):
    if (n % divisor == 0):
        print(n, ' is divisible by ', divisor)

Let's revisit an earlier example:

1
2
3

def print_if_divisible(n, divisor):
    if (n % divisor == 0):
        print(n, ' is divisible by ', divisor)

This function does two things:

1. Calculating whether an integer is divisible by another
2. Printing conditionally on the result

Let's revisit an earlier example:

1
2
3

def print_if_divisible(n, divisor):
    if (n % divisor == 0):
        print(n, ' is divisible by ', divisor)

This function does two things:

1. Calculating whether an integer is divisible by another
2. Printing conditionally on the result

These are two conceptually distinct operations. There is no good reason for them to be done in the same function.

A solution:

1
2

def is_divisible(n, divisor):
    return (n % divisor == 0)

A solution:

1
2

def is_divisible(n, divisor):
    return (n % divisor == 0)

• [CC2] Functions should do one thing

• This solution has the added benefit to remove side-effects from the function.

Example from a past student:

1
2
3
4

if shuffledtarg_dist[i][1] == 1: ### IF TARGET ###
    # [some code ...]
elif shuffledtarg_dist[i][1] == 0: ### IF DISTRACTOR ###
    # [some other code ...]

Example from a past student:

1
2
3
4

if shuffledtarg_dist[i][1] == 1: ### IF TARGET ###
    # [some code ...]
elif shuffledtarg_dist[i][1] == 0: ### IF DISTRACTOR ###
    # [some other code ...]

• Why do we need such comments next to if and elif?

Example from a past student:

1
2
3
4

if shuffledtarg_dist[i][1] == 1: ### IF TARGET ###
    # [some code ...]
elif shuffledtarg_dist[i][1] == 0: ### IF DISTRACTOR ###
    # [some other code ...]

• Why do we need such comments next to if and elif?
• Good intentions, but bad approach
• [CC4] Comments do not make up for bad code

A first solution:

1
2
3
4

if stimulus_type == STIMULUS_TYPE_TARGET:
    # [some code ...]
elif stimulus_type == STIMULUS_TYPE_DISTRACTOR:
    # [some other code ...]

A first solution:

1
2
3
4

if stimulus_type == STIMULUS_TYPE_TARGET:
    # [some code ...]
elif stimulus_type == STIMULUS_TYPE_DISTRACTOR:
    # [some other code ...]

• [CC4] Clear and expressive code with few comments is superior to obscure code with lots of comments

A first solution:

1
2
3
4

if stimulus_type == STIMULUS_TYPE_TARGET:
    # [some code ...]
elif stimulus_type == STIMULUS_TYPE_DISTRACTOR:
    # [some other code ...]

• [CC4] Clear and expressive code with few comments is superior to obscure code with lots of comments
• Can we do even better?

An even better solution:

1
2
3
4

if is_target(stimulus):
    # [some code ...]
elif is_distractor(stimulus):
    # [some other code ...]

• [CC4] Clear and expressive code with few comments is superior to obscure code with lots of comments
• Does this need any comments?

Example from a past student:

1
2
3
4

def distance_points(couple1,couple2):
    """Fonction controllant la distance entre nos points
    pour notre ensemble de points aléatoires"""
    return math.sqrt((couple1[0]-couple2[0])**2+(couple1[1]-couple2[1])**2)

Example from a past student:

1
2
3
4

def distance_points(couple1,couple2):
    """Fonction controllant la distance entre nos points
    pour notre ensemble de points aléatoires"""
    return math.sqrt((couple1[0]-couple2[0])**2+(couple1[1]-couple2[1])**2)

• Misleading comment. It does not accurately describe what the function does.

An alternative:

1

def distance_between_points(point_1, point_2)

• Does this need any comments?

Example from a past student:

1

exp = design.Experiment("Task") #create and name new exp object

Example from a past student:

1

exp = design.Experiment("Task") #create and name new exp object

• Redundant comment. This is just noise. Remove it.